---
title: Customizando Starlight
description: Aprenda como fazer seu site Starlight único com sua própria logo, fontes customizadas, design de página inicial e mais.
---

import { Tabs, TabItem } from '@astrojs/starlight/components';
import { FileTree } from '@astrojs/starlight/components';

Starlight providencia uma estilização e funcionalidades sensíveis padrões, para que você inicie rapidamente sem nenhuma configuração necessária.

Quando você quiser começar a customizar a aparência e sensação do seu site Starlight, este guia tem tudo o que você precisa.

## Adicione sua logo

Adicionar uma logo customizada ao cabeçalho do site é uma forma rápida de adicionar sua marca individual a um site Starlight.

1. Adicione o arquivo de imagem da sua logo para o diretório `src/assets/`:

   <FileTree>

   - src/
     - assets/
       - **minha-logo.svg**
     - content/
   - astro.config.mjs

   </FileTree>

2. Adicione o caminho para sua logo como a opção [`logo.src`](/pt-br/reference/configuration/#logo) do Starlight em `astro.config.mjs`:

   ```diff lang="js"
   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';

   export default defineConfig({
   	integrations: [
   		starlight({
   			title: 'Documentação com Minha Logo',
   			logo: {
   +				src: './src/assets/minha-logo.svg',
   			},
   		}),
   	],
   });
   ```

Por padrão, a logo será mostrada ao lado do `title` do seu site.
Se sua imagem da logo já inclui o título do site, você pode esconder o texto do título visualmente ao definir a opção `replacesTitle`.
O texto do `title` ainda será incluido para leitores de tela para que o cabeçalho continue acessível.

```js {5}
starlight({
  title: 'Documentação com Minha Logo',
  logo: {
    src: './src/assets/minha-logo.svg',
    replacesTitle: true,
  },
}),
```

### Variantes clara e escura da logo

Você pode mostrar diferentes versões da sua logo no modo claro e escuro.

1. Adicione um arquivo de imagem para cada variante em `src/assets/`:

   <FileTree>

   - src/
     - assets/
       - **logo-clara.svg**
       - **logo-escura.svg**
     - content/
   - astro.config.mjs

   </FileTree>

2. Adicione o caminho para suas variantes da logo como as opções `light` e `dark` ao invés de `src` em `astro.config.mjs`:

   ```diff lang="js"
   starlight({
     title: 'Documentação com Minha Logo',
     logo: {
   +    light: './src/assets/logo-clara.svg',
   +    dark: './src/assets/logo-escura.svg',
     },
   }),
   ```

## Habilitar o sitemap

O Starlight possui suporte integrado para a geração de um sitemap. Habilite a geração do sitemap definindo sua URL como `site` em `astro.config.mjs`:

```js {4}
// astro.config.mjs

export default defineConfig({
	site: 'https://stargazers.club',
	integrations: [starlight({ title: 'Site com sitemap' })],
});
```

## Layout da página

Por padrão, páginas do Starlight usam um layout com uma barra de navegação lateral global e um índice que mostra os cabeçalhos da página atual.

Você pode aplicar um layout de página maior sem barras laterais definindo [`template: splash`](/pt-br/reference/frontmatter/#template) no frontmatter de uma página.
Isso funciona particularmente bem para páginas iniciais e você pode vê-lo em ação na [página inicial deste site](/pt-br/).

```md {5}
---
# src/content/docs/index.md

title: Minha Página Inicial
template: splash
---
```

## Índice

Starlight mostra um índice para cada página para tornar mais fácil para leitores pularem ao cabeçalho no qual estão procurando.
Você pode customizar - ou até desabilitar - o índice globalmente na integração Starlight ou página a página no frontmatter.

Por padrão, cabeçalhos `<h2>` e `<h3>` são inclusos no índice. Modifique quais níveis de cabeçalho incluir ao redor do site utilizando as opções `minHeadingLevel` e `maxHeadingLevel` na [global `tableOfContents`](/pt-br/reference/configuration/#tableofcontents). Sobrescreva esses padrões em uma página individual adicionando as propriedades correspondentes do [frontmatter `tableOfContents`](/pt-br/reference/frontmatter/#tableofcontents):

<Tabs>
  <TabItem label="Frontmatter">

```md {4-6}
---
# src/content/docs/exemplo.md
title: Página com apenas H2s no índice
tableOfContents:
  minHeadingLevel: 2
  maxHeadingLevel: 2
---
```

  </TabItem>
  <TabItem label="Configuração global">

```js {7}
// astro.config.mjs

defineConfig({
	integrations: [
		starlight({
			title: 'Documentação com configuração de sumário personalizado',
			tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 2 },
		}),
	],
});
```

  </TabItem>
</Tabs>

Desabilite o índice completamente definindo a opção `tableOfContents` como `false`:

<Tabs>
  <TabItem label="Frontmatter">

```md {4}
---
# src/content/docs/exemplo.md
title: Página sem um índice
tableOfContents: false
---
```

  </TabItem>
  <TabItem label="Configuração global">

```js {7}
// astro.config.mjs

defineConfig({
	integrations: [
		starlight({
			title: 'Documentação com um índice desabilitado globalmente',
			tableOfContents: false,
		}),
	],
});
```

  </TabItem>
</Tabs>

## Links de redes sociais

Starlight tem suporte integrado para adicionar links de suas contas de redes sociais ao cabeçalho do site através da opção [`social`](/pt-br/reference/configuration/#social) na integração Starlight.

Você pode encontrar uma lista completa de ícones suportados na [Referência de Configuração](/pt-br/reference/configuration/#social).
Nos avise no GitHub ou Discord se você precisa de suporte para outro serviço!

```js {9-12}
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
	integrations: [
		starlight({
			title: 'Documentação com Links de Redes Sociais',
			social: {
				discord: 'https://astro.build/chat',
				github: 'https://github.com/withastro/starlight',
			},
		}),
	],
});
```

## Links de Edição

Starlight pode mostrar um link de "Editar página" no rodapé de cada página.
Isso faz fácil para um leitor encontrar o arquivo para editar para melhorar sua documentação.
Particularmente para projetos open-source, isso pode ajudar a encorajar contribuições da sua comunidade.

Para habilitar links de edição, defina [`editLink.baseUrl`](/pt-br/reference/configuration/#editlink) para a URL usada para editar seu repositório na configuração da integração Starlight.
O valor de `editLink.baseUrl` será anexado ao caminho para a página atual para formar o link de edição completo.

Padrões comuns incluem:

- GitHub: `https://github.com/USUARIO/REPOSITORIO/edit/BRANCH/`
- GitLab: `https://gitlab.com/USUARIO/REPOSITORIO/-/edit/BRANCH/`

Se o seu projeto Starlight não está na raiz do seu repositório, inclua o caminho ao projeto no fim da URL base.

Este exemplo mostra o link de edição configurado para a documentação do Starlight, que vive no subdiretório `docs/` da branch `main` do repositório `withastro/starlight` no GitHub:

```js {9-11}
// astro.config.mjs
import { defineConfig } from 'astro/config';
import starlight from '@astrojs/starlight';

export default defineConfig({
	integrations: [
		starlight({
			title: 'Documentação com Links de Edição',
			editLink: {
				baseUrl: 'https://github.com/withastro/starlight/edit/main/docs/',
			},
		}),
	],
});
```

## Página 404 Customizada

Sites Starlight mostram uma página 404 simples por padrão.
Você pode customizá-la adicionando um arquivo `404.md` (ou `404.mdx`) ao seu diretório `src/content/docs/`:

<FileTree>

- src/
  - content/
    - docs/
      - **404.md**
      - index.md
- astro.config.mjs

</FileTree>

Você pode utilizar todas as técnicas de customização e layout de página do Starlight em sua página 404. Por exemplo, a página 404 padrão utiliza o [template `splash`](#layout-da-página) e o componente [`hero`](/pt-br/reference/frontmatter/#hero) no frontmatter:

```md {4,6-8}
---
title: '404'
template: splash
editUrl: false
hero:
  title: '404'
  tagline: Página não encontrada. Verifique a URL ou tenta utilizar a barra de pesquisa.
---
```

## Fontes customizadas

Por padrão, Starlight utiliza fontes sans-serif disponíveis no dispositivo local do usuário para todo o texto.
Isso garante que a documentação carrega rapidamente em uma fonte que é familiar para cada usuário, sem precisar de largura de banda para baixar grandes arquivos de fonte.

Se você deve adicionar uma fonte customizada ao seu site Starlight, você pode definir fontes para usar em arquivos CSS customizados ou com qualquer outra [técnica de estilização do Astro](https://docs.astro.build/pt-br/guides/styling/).

### Configure fontes

Se você já tem arquivos de fonte, siga o [guia de configuração local](#configure-arquivos-de-fonte-locais).
Para utilizar Google Fonts, siga o [guia de configuração do Fontsource](#configure-uma-fonte-do-fontsource).

#### Configure arquivos de fonte locais

1. Adicione seus arquivos de fonte para o diretório `src/fonts/` e crie um arquivo vazio `font-face.css`:

   <FileTree>

   - src/
     - content/
     - fonts/
       - **FonteCustomizada.woff2**
       - **font-face.css**
   - astro.config.mjs

   </FileTree>

2. Adicione uma [declaração `@font-face`](https://developer.mozilla.org/pt-BR/docs/Web/CSS/@font-face) para cada uma de suas fontes em `src/fonts/font-face.css`.
   Utilize um caminho relativo para o arquivo de fonte na função `url()`.

   ```css
   /* src/fonts/font-face.css */

   @font-face {
   	font-family: 'Fonte Customizada';
   	/* Use um caminho relativo para o arquivo de fonte local em `url()`. */
   	src: url('./FonteCustomizada.woff2') format('woff2');
   	font-weight: normal;
   	font-style: normal;
   	font-display: swap;
   }
   ```

3. Adicione o caminho para seu arquivo `font-face.css` ao array `customCss` do Starlight em `astro.config.mjs`:

   ```diff lang="js"
   // astro.config.mjs
   import { defineConfig } from 'astro/config';
   import starlight from '@astrojs/starlight';

   export default defineConfig({
   	integrations: [
   		starlight({
   			title: 'Documentação Com Meu Tipo de Letra Customizado',
   			customCss: [
   +				// Caminho relativo para seu arquivo CSS @font-face.
   +				'./src/fonts/font-face.css',
   			],
   		}),
   	],
   });
   ```

#### Configure uma fonte do Fontsource

O projeto [Fontsource](https://fontsource.org/) simplifica a utilização de Google Fonts e outras fontes open-source.
Ele providencia módulos do npm que você pode isntalar para as fontes que você quer usar e inclui arquivos CSS prontos para adicionar ao seu projeto.

1.  Encontre a fonte que você quer utilizar no [catálogo do Fontsource](https://fontsource.org/).
    Este exemplo irá utilizar [IBM Plex Serif](https://fontsource.org/fonts/ibm-plex-serif).

2.  Instale o pacote da sua fonte escolhida.
    Você pode encontrar o nome do pacote clicando em “Install” na página de fontes do Fontsource.

         <Tabs>

    <TabItem label="npm">

    ```sh
    npm install @fontsource/ibm-plex-serif
    ```

           </TabItem>

        <TabItem label="pnpm">

    ```sh
    pnpm add @fontsource/ibm-plex-serif
    ```

           </TabItem>

        <TabItem label="Yarn">

    ```sh
    yarn add @fontsource/ibm-plex-serif
    ```

           </TabItem>

      </Tabs>

3.  Adicione os arquivos CSS do Fontsource ao array `customCss` do Starlight em `astro.config.mjs`:

    ```diff lang="js"
    // astro.config.mjs
    import { defineConfig } from 'astro/config';
    import starlight from '@astrojs/starlight';

    export default defineConfig({
    	integrations: [
    		starlight({
    			title: 'Documentação Com Meu Tipo de Letra Customizado',
    			customCss: [
    +				// Arquivos do Fontsource para as espessuras de fonte regular e semi-negrito.
    +				'@fontsource/ibm-plex-serif/400.css',
    +				'@fontsource/ibm-plex-serif/600.css',
    			],
    		}),
    	],
    });
    ```

    Fontsource envia múltiplos arquivos CSS para cada fonte. Veja a [documentação do Fontsource](https://fontsource.org/docs/getting-started/install#4-weights-and-styles) em como incluir diferentes espessuras e estilos para entender quais utilizar.

### Utilize fontes

Para aplicar a fonte que você definiu para o seu site, utilize o nome da sua fonte escolhida em um [arquivo CSS customizado](/pt-br/guides/css-and-tailwind/#estilos-css-customizados).
Por exemplo, para sobrescrever a fonte padrão do Starlight em todo lugar, defina a propriedade customizada `--sl-font`:

```css
/* src/styles/customizada.css */

:root {
	--sl-font: 'IBM Plex Serif', serif;
}
```

Você também pode escrever CSS mais específico se você quiser aplicar sua fonte mais seletivamente.
Por exemplo, para definir uma fonte no conteúdo principal apenas, mas não nas barras laterais:

```css
/* src/styles/customizada.css */

main {
	font-family: 'IBM Plex Serif', serif;
}
```

Siga as [instruções de CSS customizado](/pt-br/guides/css-and-tailwind/#estilos-css-customizados) para adicionar seus estilos ao seu site.
